<!--
    $Id: package.html 481833 2006-12-03 17:32:52Z niallp $

    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at
   
         http://www.apache.org/licenses/LICENSE-2.0
   
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-->
<html>
<head>
    <title>Package Documentation for org.apache.struts.util Package</title>
</head>

<body bgcolor="white">
The Utilities package provides a variety of families of classes,
to solve problems that are commonly encountered in building web applications.
<br><br>
<a name="doc.Description"></a>

<div align="center">
    <a href="#doc.Intro">[Introduction]</a>
    <a href="#doc.Beans">[Beans]</a>
    <a href="#doc.Utilities">[Servlet Utilities]</a>
    <a href="#doc.Messages">[Message Resources]</a>
</div>

<hr>

<a name="doc.Intro"></a>

<h3>Introduction</h3>

<p>The Struts Utilities Package offers several families
    of classes that assist in solving commonly encountered problems when
    building
    web applications. Most of the classes in this package do not rely on the
    controller servlet framework, or the custom tag libraries, so they are
    also
    suitable for general Java application programming. The following families
    are included:</p>
<ul>
    <li><a href="#doc.Beans">Beans</a> - A small set of utility beans useful
        for
        encapsulating form elements.</li>
    <li><a href="#doc.Utilities">Servlet Utilities</a> - A set of classes
        useful
        for working with servlet-related classes.</li>
    <li><a href="#doc.Messages">Message Resources</a> - A family of classes
        that
        features access to internationalized message strings based on a
        message
        key coupled with a <code>java.util.Locale</code> object representing a
        particular user's preferred language.</li>
</ul>

<hr>

<a name="doc.Beans"></a>

<h3>Beans</h3>

<p> The <code>ImageButtonBean</code> is a simple JavaBean to encapsulate the
    request parameters sent for an HTML input element of type image. The
    <code>LabelValueBean</code> is a simple JavaBean to represent label-value
    pairs, especially useful for html option elements.
</p>

<hr>

<a name="doc.Utilities"></a>

<h3>Servlet Utilities</h3>

<p> The <code>RequestUtils</code> is a general purpose utility methods
    related to processing a servlet request. The <code>ResponseUtils</code>
    is a general purpose utility methods related to generating a servlet
    response. The <code>ServletContextWriter</code> is a PrintWriter
    implementation that uses the logging facilities of a
    <code>javax.servlet.ServletContext</code> to output its results.
</p>

<hr>

<a name="doc.Messages"></a>

<h3>Message Resources</h3>

<h5>Background</h5>

<p>Modern applications often include the requirement to support multiple
    languages, for users who prefer to interact in a language other than the
    default language configured on the server platform. In addition, sentences
    often need to be constructed, with dynamic content whose placement in the
    message depends on the standard sentence structure in that particular
    language.</p>

<p>The standard Java platform includes a family of classes
    (<code>java.util.ResourceBundle</code>) designed to support looking up
    message
    strings based on a standard "key". The resource bundle classes
    automatically
    access a Java class (or properties file) that is named with a naming
    convention that includes the Locale to which messages in that class (or
    file)
    pertain. However, this selection is based only on the default Locale of
    the
    server platform, and cannot be adjusted on a per-user basis as required
    for an
    internationalized web application.</p>

<p>Struts includes a family of classes
    (<code>org.apache.struts.util.MessageResources</code>) that extends the
    basic
    approach to looking up message strings by key, allowing you to optionally
    specify a Locale along with the key. In this way, you can build
    applications
    that let your users select which Locale they wish to operate within, and
    then
    look up messages in that language - using the same message keys no matter
    what
    language is selected.</p>

<p>In addition to supporting dynamic selection of a Locale for message lookup,
    the <code>MessageResources</code> family of classes optionally allow you
    to
    specify up to four parameter replacement objects, which are used to
    replace the
    parameter placeholders "{0}" through "{3}" in the retrieved message. This
    replacement uses the facilities of the standard Java
    <code>java.text.MessageFormat</code> class, which supports many extended
    formatting capabilities as well.</p>

<p>For more information about internationalized messages, consult the
    following
    resources in your Java Development Kit documentation bundle:</p>
<ul>
    <li><em>Internationalization Info</em> - General information on Java's
        standard
        support for internationalized applications can be found at
        <code>&lt;$JAVA_HOME/docs/guide/internat/index.html&gt;</code>.
        The "Internationalization Overview" section includes useful
        information
        about Locales, localized resources, message formatting, and other
        relevant topics.</li>
    <li><em>Internationalization Tutorial</em> - The Java Language Tutorial
        has a
        comprehensive trail covering internationalization, available at:
        <a href="http://java.sun.com/docs/books/tutorial/i18n/index.html">
            http://java.sun.com/docs/books/tutorial/i18n/index.html</a>.</li>
    <li><em>Javadoc APIs</em> - You will want to consult the Javadoc API
        documentation for the following standard Java classes:
        <ul>
            <li><code>java.text.MessageFormat</code>
            <li><code>java.util.ResourceBundle</code>
            <li><code>java.util.PropertyResourceBundle</code>
            <li><code>java.util.Properties</code> - See the documentation for
                the
                <code>load()</code> method for the valid syntax of properties
                files
                that you prepare.</li>
        </ul></li>
</ul>

<h5>Using the Standard MessageResources Implementation</h5>

<p>The standard <code>MessageResources</code> implementation provided by the
    Struts library uses Java properties files to initialize message strings,
    in a
    manner very similar to that supported by the
    <code>java.util.PropertyResourceBundle</code> class. The following steps
    are
    required to use these facilities in your Java application.</p>

<p>First, prepare a Java properties file for each language (or Locale) in
    which
    you wish to support your messages. The filenames you use must conform to
    the
    naming convention for property resource bundles, as described in the
    documentation referenced above. Be sure you use the same message keys in
    each
    file to identify the same message.</p>

<p>For example, you might prepare files in French, Spanish, and English that
    contain language-specific versions of the word "Hello". The French file
    would
    be named <code>Messages_fr.properties</code> and contain the following:
</p>
<pre>
    hi=Bonjour
</pre>

<p>while the Spanish and English files would be named
    <code>Messages_es.properties</code> and <code>
    Messages_en.properties</code>
    respectively. The corresponding message string definitions would say
    <code>hi=Hola</code> and <code>hi=Hello</code> in these files.</p>

<p>Second, place these properties files into the class path for your
    application, exactly as you would with class files themselves. The name
    actually used to load resources will look like a fully qualified Java
    class
    name (with appropriate package prefixes), so the file should be nested
    inside
    a directory structure that matches the packaging (either in an unpacked
    directory, or within a JAR file, as appropriate). For example, assume you
    place directory "foo" on your classpath, and stored the above properties
    files
    in directory "foo/com/mycompany/mypackage". (If you were using a JAR file
    like
    "foo.jar" instead, the files would be in directory
    "com/mycompany/mypackage"
    within the JAR file).

<p>Third, initialize a <code>MessageResources</code> object that corresponds
    to the set of properties files for a particular name, within a particular
    package. The easiest way to do this is to initialize a variable in your
    main
    application class, like this:</p>
<pre>
    public static MessageResources messages =
    MessageResources.getMessageResources("com.mycompany.mypackage.Messages");
</pre>

<p>Note that the "com.mycompany.mypackage" part of the name matches the
    package
    directory into which you placed your properties files, and "Messages" is
    the
    filename prefix for the particular family of properties files supported by
    this
    <code>MessageResources</code> instance. Depending on your development
    process,
    you might find it convenient to store all message strings for an entire
    application in a single properties file family, or to have several
    families -
    in Struts, for example, there is a family of properties files for each
    Java
    package.</p>

<p>To access a message string with a particular Locale, execute a statement
    like this:</p>
<pre>
    Locale locale = ... select the locale to be used ...
    String message = messages.getMessage(locale, "hi");
</pre>

<p>In this case, the variable <code>message</code> will contain the message
    string corresponding to the key "hi", in the language that corresponds to
    the
    locale that was selected.</p>

<p>For an example of message formatting with replaceable parameters, assume
    that the message strings looked like this, instead (only the English
    version
    is shown - corresponding changes would be made in the other files):</p>
<pre>
    hi=Hello {0}
</pre>

<p>Now, you can personalize the retrieved message like this:</p>
<pre>
    Locale locale = ... select the locale to be used ...
    String name = "Joe";
    String message = messages.getMessage(locale, "hi", name);
</pre>

<p>and the marker "{0}" will have been replaced by the specified name (Joe),
    no matter which language is in use. See the JavaDoc API documentation for
    the
    <code>java.text.MessageFormat</code> class for more advanced uses of the
    parameter replacement mechanism.</p>

<h5>Developing Your Own MessageResources Implementation</h5>

<p>In the above example, we were using the default
    <code>MessageResources</code> implementation supplied by Struts, which
    uses
    property files to store the message strings. It is also possible to create
    customized mechanisms to retrieve messages (such as loading them on demand
    from a database). The steps required are as follows:</p>
<ul>
    <li>Create a customized subclass of
        <code>org.apache.struts.util.MessageResources</code> that implements
        message lookup operations as you require.</li>
    <li>Create a customized subclass of
        <code>org.apache.struts.util.MessageResourcesFactory</code> that will
        create an instance of your custom <code>MessageResources</code> class
        when the <code>createResources</code> method is called. Note that the
        "config" argument to this method can be used to select families of
        messages in any manner appropriate to your needs - you are not
        required
        to emulate the "fully qualified Java class name" approach that is used
        by the standard <code>PropertyMessageResourcesFactory</code> class.
    </li>
    <li>Tell the <code>MessageResourcesFactory</code> class the name of the
        customized <code>MessageResourcesFactory</code> implementation to use
        when creating new factory instances.</li>
    <li>Create a new factory instance.</li>
    <li>Ask the new factory instance to create a <code>MessageResources</code>
        instance for you.</li>
</ul>

<p>A code example that illustrates this technique is:</p>
<pre>
    MessageResourcesFactory.setFactoryClass("com.mycompany.mypkg.MyFactory");
    MessageResourcesFactory factory = MessageResourcesFactory.createFactory();
    MessageResources resources =
    factory.createResources("configuration information");
</pre>

<p>Once you have created your custom MessageResources instance, you utilize it
    to access message strings (with or without parameter replacement objects),
    exactly as we illustrated with the standard implementation in the previous
    section.</p>

<h5>Using MessageResources With Struts</h5>

<p>If your application uses the Struts controller servlet, you can optionally
    configure Struts to load an application-specific message resources
    instance for
    you, and make it available as a servlet context attribute (in JSP terms,
    an
    application-scope bean). This mechanism is managed by setting the
    following
    servlet initialization parameters in the web application deployment
    descriptor:
</p>
<ul>
    <li><strong>application</strong> - The configuration string that will be
        passed to the <code>createResources()</code> method of the message
        resources factory, in order to identify the family of resources to be
        supported. If you use the standard message resources factory, this
        must
        be the base fully qualified name of the property resources files used
        to contain these messages, as illustrated above.</li>
    <li><strong>factory</strong> - Fully qualified Java class name of the
        <code>MessageResourcesFactory</code> to be used. By default, the
        standard
        implementation provided by Struts
        (<code>org.apache.struts.util.PropertyMessageResourcesFactory</code>)
        will be used.</li>
</ul>

<p>Struts provides several JSP custom tags that assume the existence of a
    <code>java.util.Locale</code> attribute in the user's session, under the
    key
    named by the constant string value of <code>Action.LOCALE_KEY</code>. Your
    own
    application logic can set this attribute at any time, or you can ask
    Struts to
    set it automatically (if not already set) based on the
    <code>Accept-Language</code> HTTP header included with the request. There
    are
    two mechanisms by which you request Struts to perform this service:</p>
<ul>
    <li>To have this service performed on every request submitted to the
        controller
        servlet, set the servlet initialization parameter <code>locale</code>
        to
        the value <code>true</code> in the application deployment descriptor.
    </li>
    <li>To have this service performed by a JSP page when it is accessed
        directly
        by a user, utilize a <code>&lt;form:html ... locale="true" ...
        /&gt;</code>
        tag at the top of each page.</li>
</ul>

</body>
</html>
